CATcoverage API from Poulton Associates

New Business Application Support Methods

Support methods used in the workflow of a new business application.

This page provides information about using the support methods that give available options for data points, as well as insurance application specific information needed to complete steps in the new business application workflow.

Click here to view the new business application workflow that these methods are intended to support.

Prerequisites

Before you start this walk-through:

  • Install Postman
    • This can be downloaded at: https://www.postman.com/downloads/
      • You don't need to sign in or create an account.
        • Just look for the alternate options to skip sign-in when prompted (it can be really small and inconspicuous).
  • Open Postman and import our example collection that accompanies this walk-through.
    • Download our Postman collection
    • Open Postman (skip the sign-in, or sign in with your account), click the "Import" button at the top-left of the window and select the collection file just downloaded.
    • After importing, you should see the "CATcoverage API v2 - New Biz" collection in the list at the left.
  • Obtain a client ID and secret.
    • The Postman example requests automatically fetch a client access token as necessary for authorization.
    • The "Variables" tab in the collection has variables for clientId and clientSecret that must be filled in or else the requests will all return with 401 (unauthorized) responses.

Get Broad Line of Business Options

Gets the available broad lines of business for risks in the CATcoverage system.

api/v2/Product/broadLineOfBusiness

  • In the Postman collection, open the request named "Get Broad Line of Business Options".
  • Note that there is no request body, so also no need to set a request content type header. There are also no URL parameters.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of the broad lines of business.

response description

The response should contain a list of items with these properties:

  • id
    • A GUID for identifying this option.
  • displayName
    • A user-friendly name for this broad line of business.
  • code
    • The system code for this broad line of business.
    • Use this to identify this broad line of business whenever it is required input for another API.

Get Perils Deductibles Allowed

Gets the allowed perils and the deductibles allowed for each peril for a given situation.

api/v2/Product/possible-perils-deductibles/{broadLobCode}/{stateCode}

  • In the Postman collection, open the request named "Get Perils Deductibles Allowed".
  • Note that there is no request body, so also no need to set a request content type header.
    • The broadLobCode for the line of insurance (personal or commercial) is provided in the request URL.
    • The stateCode representing the U.S. state in which the risk property resides is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of perils and deductibles allowed for the given situation.

response description

The response should contain a list of items with these properties:

  • perilName
    • A user-friendly name for this peril option.
  • perilCode
    • The code for this peril option.
    • Use this as the value provided to API methods needing a peril code (such as for getting a price indication).
  • isAllowedAtLocation
    • If false, this peril cannot be selected in this U.S. state.
  • allowedDeductibleCodes
    • A list of deductible codes that can be selected for this peril.

Get Disqualifiers

Gets the disqualifying conditions for a given new business application.
These must be acknowledged to not apply to the risk before coverage may be accepted. Claims may be denied and coverage canceled if it is determined that any of these disqualifying conditions existed when coverage was extended.
The specific items returned will depend on the specific new business application.

api/v2/Product/disqualifiers?perilCodes={PerilCodes}&broadLineOfBusiness={RES or COMM}&version={DisqualifierTextVersion}

  • In the Postman collection, open the request named "Get Disqualifiers".
  • Note that there is no request body, so also no need to set a request content type header.
    • The perilCodes for the line of insurance (personal or commercial) are provided in the request URL.
      • Note that these are a list for the same variable. To include multiple perils, separate them with commas.
        • Example "disqualifiers?perilCodes=EQ,FL"
    • The broadLineOfBusiness is provided in the request URL.
      • This is either "RES" for personal lines or "COMM" for commercial lines.
        • Example "disqualifiers?perilCodes=EQ,FL&broadLineOfBusiness=RES"
    • The disqualifierTextVersion is provided in the request URL but is optional.
      • This should be left out (not provided) when calling this method in the typical new business application workflow.
      • When the DisqualifierTextVersion is not specified, it will default to the latest. The version will be incremented whenever the disqualifier texts are updated.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the disqualifier texts in the result.

response description

The response data should contain:

  • version
    • A version number to identify the specific text acknowledged later after the disqualifiers may have changed.
  • preambleTexts
    • A list of texts representing the text that should be displayed to the insured (or a producer representing them) before the disqualifying items themselves are displayed.
  • conditionTexts
    • A list of texts representing the disqualifying items that must each be acknowledged as false for any coverage to be extended.
  • postTexts
    • A list of texts representing the text that should be displayed to the insured (or a producer representing them) after the disqualifying items themselves are displayed.

Get Valid Inception Date Boundaries

Provides the current allowed date range for setting the requested inception date for a new business application.
By default, all new business applications will start out with the current date and the resulting policy term will begin the day that payment is made in full for the new policy.
If the insured, or the mortgagee of the risk property, wants the policy term to begin on a specific date, the requested inception date may be set to any date within the range provided by the result of this method.
Note that coverage will not begin until the later of either the requested inception date or the date that payment is accepted in full for the policy term.

api/v2/Product/inception-date/valid-date-bounds

  • In the Postman collection, open the request named "Get Disqualifiers".
  • Note that there is no request body, so also no need to set a request content type header. There are also no URL parameters.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the valid date bounds in the result.

response description

The response data should contain 2 dates for the earliest and latest dates allowed.
Note that there are no time elements, meaning these dates are the actual beginning and end date allowed to be selected for the requested inception date at the time this method was invoked.

  • earliestDateAllowed
    • The earliest date allowed.
  • latestDateAllowed
    • The latest date allowed.

Get Construction Type Options

Provides a list of the valid construction type options for a property to be insured.

api/v2/Product/constructionType/{broadLineOfBusiness}

  • In the Postman collection, open the request named "Get Construction Type Options".
  • Note that there is no request body, so also no need to set a request content type header.
    • The broadLineOfBusiness for the line of insurance (personal or commercial) is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of the valid construction types in the result.

response description

The response data should contain a list of items with these properties:

  • displayName
    • A user-friendly name for this construction type.
  • code
    • The system code for this construction type.
    • Use this to identify this construction type whenever it is required input for another API.

Get Foundation Detail Options

Provides a list of the valid foundation detail type options for a property to be insured.
Note that we have a method to get foundation types that include the foundation detail options per type, as well as this method to just get the list of all possible foundation detail types.
None of our API v2 methods require selecting a foundation type, but some may require selecting the foundation detail type for a property.
Being able to categorize the details by foundation type is just for the convenience of users selecting these options in a user interface.

api/v2/Product/buildingFoundationDetail/{broadLineOfBusiness}

  • In the Postman collection, open the request named "Get Foundation Detail Options".
  • Note that there is no request body, so also no need to set a request content type header.
    • The broadLineOfBusiness for the line of insurance (personal or commercial) is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of the valid foundation detail types in the result.

response description

The response data should contain a list of items with these properties:

  • displayName
    • A user-friendly name for this foundation detail item.
  • code
    • The system code for this foundation detail item.
    • Use this to identify this foundation detail whenever it is required input for another API.

Get Foundation Options

Provides a list of foundation types, each containing all possible foundation detail options for the given foundation type.
Note that we have this method to get foundation types that include the foundation detail options per type, as well as a method to just get the list of all possible foundation detail types.
None of our API v2 methods require selecting a foundation type, but some may require selecting the foundation detail type for a property.
Being able to categorize the details by foundation type is just for the convenience of users selecting these options in a user interface.

api/v2/Product/buildingFoundation/{broadLineOfBusiness}

  • In the Postman collection, open the request named "Get Foundation Options".
  • Note that there is no request body, so also no need to set a request content type header.
    • The broadLineOfBusiness for the line of insurance (personal or commercial) is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of foundation type and their detail items in the result.

response description

The response data should contain a list of items with these properties:

  • displayName
    • A user-friendly name for this foundation type item.
  • code
    • The system code for this foundation type item.
  • possibleBuildingFoundationDetails
    • A list of all foundation detail items that fit within this foundation type.
    • These can also be obtained with the "Get Foundation Detail Options" method described above, consolidated and without the parent foundation types.
      • See the details above for a description of this information.
    • The foundation detail codes are what may be required by other API methods to update the foundation detail for a given risk property.

Get Building Use Options

Provides a list of the valid building use options for a property to be insured.
It's important to note that these options for commercial vs. personal lines risks are completely different.

api/v2/Product/buildingUse/{broadLineOfBusiness}

  • In the Postman collection, open the request named "Get Building Use Options".
  • Note that there is no request body, so also no need to set a request content type header.
    • The broadLineOfBusiness for the line of insurance (personal or commercial) is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of the valid building use options in the result.

response description

The response data should contain a list of items with these properties:

  • displayName
    • A user-friendly name for this building use item.
  • code
    • The system code for this building use item.
    • Use this to identify the building use whenever it is required input for another API.

Get Building Occupancy Options

Provides a list of the valid building use options for a property to be insured.
It's important to note that these options for commercial vs. personal lines risks are completely different.

api/v2/Product/buildingOccupancy/{broadLineOfBusiness}

  • In the Postman collection, open the request named "Get Building Occupancy Options".
  • Note that there is no request body, so also no need to set a request content type header.
    • The broadLineOfBusiness for the line of insurance (personal or commercial) is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of the valid building occupancy options in the result.

response description

The response data should contain a list of items with these properties:

  • displayName
    • A user-friendly name for this building occupancy item.
  • code
    • The system code for this building occupancy item.
    • Use this to identify the building occupancy whenever it is required input for another API.

Get Parking Type Options

Provides a list of the valid parking type options for a property to be insured.
Currently, this is only used for commercial property risks.
It won't return any values for personal lines because nothing requires this for that line of business.

api/v2/Product/buildingParkingType/{broadLineOfBusiness}

  • In the Postman collection, open the request named "Get Parking Type Options".
  • Note that there is no request body, so also no need to set a request content type header.
    • The broadLineOfBusiness for the line of insurance (personal or commercial) is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of the valid parking type options in the result.

response description

The response data should contain a list of items with these properties:

  • displayName
    • A user-friendly name for this building occupancy item.
  • code
    • The system code for this parking type item.
    • Use this to identify the parking type whenever it is required input for another API.

Get Policy Notes

Returns all notes attached to the given policy or new business application.
For new business applications, this is mostly used to get messages from underwriting after a risk has been submitted for coverage consideration.

api/v2/PolicyNote/policy/{policyId}

  • In the Postman collection, open the request named "Get Policy Notes".
  • Note that there is no request body, so also no need to set a request content type header.
    • The policyId is provided in the request URL. This is the same as the application ID for new business applications.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response and the result should contain a list of any notes attached to the policy or new business application.

response description

The response data should contain a list of note items for the specified policy/application.
Most of the properties are only needed for CATcoverage admin purposes.
The following properties are of special note when retrieving notes from underwriting about the status of a new business application:

  • note
    • A text note.
    • For new business applications, this will contain any messages from underwriting with explanations of the current status or requests for more information.
  • dateSubmit
    • The date the note was created/submitted.
  • docName
    • If a document was attached along with the note, this will contain the name of the document.
  • underwriterAction
    • If the note was added to describe a new business application status update by underwriting, this will identify the action taken (such as being approved or declined).